---
title: Zoom Plugin
description: Add zooming capabilities like zoom in, zoom out, fit-to-page, and marquee (area) zoom to your PDF viewer.
searchable: true
---

import { Callout } from '@/components/callout'

# Zoom Plugin

The Zoom Plugin provides a comprehensive set of tools for controlling the magnification of PDF documents. It supports standard zoom-in/out, preset zoom levels (like fit-to-page and fit-to-width), and an interactive marquee zoom (also known as area zoom).

## Installation

This plugin is available as a separate package. You'll also need the `interaction-manager` plugin if you plan to use the marquee zoom feature.

```sh npm2yarn
npm install @embedpdf/plugin-zoom @embedpdf/plugin-interaction-manager
````

## Registration

Import `ZoomPluginPackage` and, if needed, `InteractionManagerPluginPackage`. Add them to the `plugins` array passed to the `<EmbedPDF>` component. You can configure the default zoom behavior upon registration.

```tsx {4-7, 23-26}
import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/react'
// ... other imports
import {
  ZoomPluginPackage,
  ZoomMode,
} from '@embedpdf/plugin-zoom/react'
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/react'

const plugins = [
  // ... other essential plugins like Loader, Viewport, etc.
  createPluginRegistration(LoaderPluginPackage, {
    /* ... */
  }),
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Register the interaction manager (required for marquee zoom)
  createPluginRegistration(InteractionManagerPluginPackage),

  // Register and configure the zoom plugin
  createPluginRegistration(ZoomPluginPackage, {
    // Set the initial zoom level when a document loads
    defaultZoomLevel: ZoomMode.FitPage,
  }),
]

// ... rest of your component
```

## Usage

The plugin exposes the `useZoom` hook to connect your UI components to its logic and state, and the `<MarqueeZoom />` component for area selection.

### Building a Zoom Toolbar

The `useZoom` hook is the primary way to interact with the plugin. It returns the current zoom `state` and a `provides` object with methods to change the zoom.

Here's how you can build a custom toolbar:

```tsx filename="ZoomToolbar.tsx"
import { useZoom } from '@embedpdf/plugin-zoom/react'

export const ZoomToolbar = () => {
  const { provides: zoom, state } = useZoom()

  if (!zoom) {
    return null
  }

  return (
    <div className="toolbar">
      {/* Display current zoom */}
      <span>{Math.round(state.currentZoomLevel * 100)}%</span>

      {/* Buttons to control zoom */}
      <button onClick={zoom.zoomOut}>-</button>
      <button onClick={zoom.zoomIn}>+</button>
      <button onClick={() => zoom.requestZoom(1.0)}>Reset</button>

      {/* Button to toggle area zoom mode */}
      <button onClick={zoom.toggleMarqueeZoom}>Area Zoom</button>
    </div>
  )
}
```

<Callout type="info">
To have the "Area Zoom" button visually reflect its active state, you would also use a hook from the **Interaction
Manager** plugin to check the currently active mode.
</Callout>

### Adding Marquee (Area) Zoom

The marquee zoom feature allows users to click and drag a rectangle on a page to zoom into that specific area.

To enable this, place the `<MarqueeZoom />` component inside the `renderPage` prop of your `<Scroller />`. This component will automatically render the selection rectangle when the marquee mode is active.

```tsx {1, 6-12, 19, 20}
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/react';

// Inside your main PDFViewer component
<Scroller
  renderPage={({ width, height, pageIndex, scale, rotation }) => (
    <PagePointerProvider
      pageIndex={pageIndex}
      pageWidth={width}
      pageHeight={height}
      rotation={rotation}
      scale={scale}
    >
      {/* Base render layer - renders a low resolution version of the entire page for immediate display */}
      <RenderLayer pageIndex={pageIndex} scale={1} />

      {/* Tiling layer - renders high resolution tiles only for the visible area, scales with zoom level */}
      <TilingLayer pageIndex={pageIndex} scale={scale} />

      {/* Marquee layer for area zoom */}
      <MarqueeZoom pageIndex={pageIndex} scale={scale} />
    </PagePointerProvider>
  )}
/>
```

This requires the `interaction-manager` plugin to be registered. When a user clicks the "Area Zoom" button in the toolbar, `toggleMarqueeZoom` activates the mode, and the `<MarqueeZoom />` component handles the user's drag-and-drop interaction.

## Live Example

This example combines the toolbar and the marquee zoom component into a complete viewer. Try clicking the area zoom button (the icon with the magnifying glass and crosshairs) and dragging a rectangle over the document.

import { PDFViewer } from '../code-examples/zoom-example'

<PDFViewer withMarqueeZoom={true} />

## API Reference

### Configuration (`ZoomPluginConfig`)

You can pass these options when registering the plugin with `createPluginRegistration`:

| Option | Type | Description |
| :--- | :--- | :--- |
| **`defaultZoomLevel`** | `ZoomMode \| number` | The initial zoom level. Can be a numeric scale factor (e.g., `1.5` for 150%) or a `ZoomMode` enum (`ZoomMode.Automatic`, `ZoomMode.FitPage`, `ZoomMode.FitWidth`). <br />**Default**: `ZoomMode.Automatic` |
| **`minZoom`** | `number` | The minimum allowed numeric zoom level. <br />**Default**: `0.2` |
| **`maxZoom`** | `number` | The maximum allowed numeric zoom level. <br />**Default**: `60` |
| **`presets`** | `ZoomPreset[]` | An array of objects `{ name: string, value: ZoomMode \| number }` to define options for a zoom dropdown menu in your UI. Use `provides.getPresets()` to retrieve this list. |

### Hook: `useZoom()`

This hook connects your component to the zoom plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`state`** | `ZoomState` | An object containing the current zoom state. |
| **`provides`** | `ZoomCapability \| null` | An object with methods to control zooming, or `null` if the plugin is not ready. |

#### `ZoomState` Properties

| Property | Type | Description |
| :--- | :--- | :--- |
| **`currentZoomLevel`** | `number` | The actual, calculated zoom factor applied to the document. |
| **`zoomLevel`** | `ZoomMode \| number` | The last *requested* zoom level, which might be a mode like `'fit-page'`. |

#### `ZoomCapability` Methods

| Method | Description |
| :--- | :--- |
| **`zoomIn()`** | Zooms in by one step. |
| **`zoomOut()`** | Zooms out by one step. |
| **`requestZoom(level)`** | Sets the zoom to a specific level (e.g., `1.0` or `ZoomMode.FitWidth`). |
| **`toggleMarqueeZoom()`** | Enables or disables the area zoom mode. |
| **`isMarqueeZoomActive()`** | Returns `true` if area zoom is currently active. |
| **`getPresets()`** | Returns the array of presets from the configuration. |

### Component: `<MarqueeZoom />`

Renders the visual rectangle when a user is selecting an area to zoom into.

#### Props

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | (Required) The index of the page this component is rendered on. |
| **`scale`** | `number` | (Required) The current scale of the page. |
| **`className`** | `string` | (Optional) An optional CSS class for custom styling of the marquee rectangle. |
| **`stroke`** | `string` | (Optional) The color of the rectangle's border. |
| **`fill`** | `string` | (Optional) The background color of the rectangle. |
